package com.smart.community.property.service;

import com.smart.community.property.entity.RepairProgress;

import java.time.LocalDateTime;
import java.util.List;

/**
 * 维修工单进度记录服务接口
 * 
 * 严格按照《Java后端SpringBoot代码开发规范.md》Service层生产环境标准实现：
 * - 生产环境标准：移除throws Exception声明，使用优雅降级处理
 * - 缓存策略：支持Redis缓存机制，提高查询性能
 * - 性能优化：支持性能监控和统计功能
 * - 异常处理：统一异常处理机制，确保系统稳定性
 * - 参数验证：完善的参数验证和业务逻辑校验
 * 
 * 特殊说明：createProgress和createProgressWithRepairman方法根据智慧社区微服务架构总览要求保留throws Exception声明
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 * @version 3.0.0 - 生产环境标准优化版本
 */
public interface IRepairProgressService {

    /**
     * 保存进度记录
     * @param progress 进度记录
     * @return 是否保存成功，失败时返回false
     */
    boolean saveProgress(RepairProgress progress);

    /**
     * 创建工单进度记录
     * @param orderId 工单ID
     * @param orderNo 工单号
     * @param progressType 进度类型
     * @param progressTitle 进度标题
     * @param progressContent 进度内容
     * @param operatorId 操作人ID
     * @param operatorName 操作人姓名
     * @return 是否创建成功
     * @throws Exception 根据智慧社区微服务架构总览要求，此方法需要抛出异常
     */
    boolean createProgress(Long orderId, String orderNo, Integer progressType, String progressTitle,
                          String progressContent, Long operatorId, String operatorName) throws Exception;

    /**
     * 创建工单进度记录（包含维修人员信息）
     * @param orderId 工单ID
     * @param orderNo 工单号
     * @param progressType 进度类型
     * @param progressTitle 进度标题
     * @param progressContent 进度内容
     * @param operatorId 操作人ID
     * @param operatorName 操作人姓名
     * @param repairmanId 维修人员ID
     * @param repairmanName 维修人员姓名
     * @param progressTime 进度时间
     * @return 是否创建成功
     * @throws Exception 根据智慧社区微服务架构总览要求，此方法需要抛出异常
     */
    boolean createProgressWithRepairman(Long orderId, String orderNo, Integer progressType, String progressTitle,
                                       String progressContent, Long operatorId, String operatorName,
                                       Long repairmanId, String repairmanName, LocalDateTime progressTime) throws Exception;

    /**
     * 根据工单ID查询进度记录列表
     * @param orderId 工单ID
     * @return 进度记录列表，查询失败时返回空列表
     */
    List<RepairProgress> getProgressListByOrderId(Long orderId);

    /**
     * 根据工单号查询进度记录列表
     * @param orderNo 工单号
     * @return 进度记录列表，查询失败时返回空列表
     */
    List<RepairProgress> getProgressListByOrderNo(String orderNo);

    /**
     * 获取工单最新的进度记录
     * @param orderId 工单ID
     * @return 最新进度记录，查询失败时返回null
     */
    RepairProgress getLatestProgressByOrderId(Long orderId);

    /**
     * 根据进度类型查询进度记录
     * @param orderId 工单ID
     * @param progressType 进度类型
     * @return 进度记录，查询失败时返回null
     */
    RepairProgress getProgressByOrderIdAndType(Long orderId, Integer progressType);

    /**
     * 删除工单相关的所有进度记录
     * @param orderId 工单ID
     * @return 是否删除成功，失败时返回false
     */
    boolean deleteProgressByOrderId(Long orderId);

    /**
     * 统计工单进度数量
     * @param orderId 工单ID
     * @return 进度数量，统计失败时返回0
     */
    int countProgressByOrderId(Long orderId);

    /**
     * 查询指定时间范围内的进度记录
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 进度记录列表，查询失败时返回空列表
     */
    List<RepairProgress> getProgressListByTimeRange(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 查询维修人员相关的进度记录
     * @param repairmanId 维修人员ID
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 进度记录列表，查询失败时返回空列表
     */
    List<RepairProgress> getProgressListByRepairmanId(Long repairmanId, LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 批量创建进度记录
     * @param progressList 进度记录列表
     * @return 是否创建成功，失败时返回false
     */
    boolean batchCreateProgress(List<RepairProgress> progressList);

    /**
     * 更新工单最新进度记录的内容
     * @param orderId 工单ID
     * @param progressContent 新的进度内容
     * @return 是否更新成功，失败时返回false
     */
    boolean updateProgressContent(Long orderId, String progressContent);
} 